home *** CD-ROM | disk | FTP | other *** search
/ Macwelt 1 / Macwelt DVD 1.toast / Web-Publishing / HTML-Editoren / Alpha ƒ / Help / ManipCols Help < prev    next >
Encoding:
Text File  |  2000-12-08  |  21.0 KB  |  494 lines
  1. This file : manipCols Help 
  2.         Created : 27 mai 2000 - 8:28:25 
  3.         Last modification : 6 octobre 2000 - 11:16:32
  4. Author : Bernard Desgraupes 
  5. e-mail : <berdesg@easynet.fr> 
  6. Web-page : <http://perso.easynet.fr/~berdesg/> 
  7.  
  8. Comments :  help file for the columns manipulation package in Alpha.
  9. This file should be located in the Help subfolder of Alpha's folder
  10. to show up automatically in the Help menu when Alpha is loaded.  
  11.  
  12. (c) Copyright : Bernard Desgraupes 2000
  13.  
  14. This program is free software; you can redistribute  it  and/or  modify  it
  15. under the terms of the GNU General  Public  License  as  published  by  the
  16. Free Software Foundation; either version 2 of the  License,  or  any  later
  17. version :
  18.     <http://www.gnu.org/copyleft/gpl.html> 
  19. This program is distributed in the hope that it  will  be  useful,      but
  20. WITHOUT ANY WARRANTY; without even the    implied            warranty    of
  21. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the   GNU  General
  22. Public License for more details.
  23.  
  24. You should have received a copy of the GNU  General  Public  License  along
  25. with this program; if not, write  to  the  FreeSoftware  Foundation,  Inc.,
  26. 675 Mass Ave, Cambridge, MA 02139, USA.
  27.  
  28. Contents:
  29. ______________
  30. • Introduction
  31. • Basics
  32. • Installation
  33. • Menu Items
  34. • Key Bindings
  35. • Preferences
  36. • Version History
  37. • More Cols Package
  38. • Known problems
  39. ______________
  40.  
  41.  
  42. ====================
  43. Introduction
  44. ====================
  45.  
  46. The 'manipCols' package is a feature which    allows    to    do    various
  47. manipulations with the columns of any tabulated material i-e  a  series  of
  48. lines in which items are separated by a tabulation or by any other specific
  49. character (like & or a tabulation or a colon, a comma, an  endash  etc.  or
  50. even the space character). Once it is installed and activated,  it  adds  a
  51. submenu called <Columns> to the <Text> menu in Alpha.  The  items  of  this
  52. submenu are explained below. Basic manipulations  are  copying,  inserting,
  53. appending, twiddling,  deleting,  sorting,  numbering  and  (un/)equalizing
  54. columns, formating text in columns.
  55.  
  56.  
  57. ============
  58. Basics
  59. ============
  60.  
  61. -Columns selection-
  62. to select one or several columns, put the cursor anywhere in  the  text  of
  63. the top left item (or "cell") you want to select, press  the  mouse  button
  64. and,  without releasing the button, go to the text of the bottom right item
  65. you want to select.
  66. This will hilite a region which is much more than what  you  want  but  the
  67. package will consider only the columns located between the top  and  bottom
  68. positions.
  69. Here is an example (from Romeo and Juliet). We suppose here that each  word
  70. is separated by a tabulation (any single  character  can  be  chosen  as  a
  71. separator, even the space character; see below) :
  72. Gallop    apace,    you    fiery-footed    steeds,
  73. Towards    Phoebus'    lodging;    such    a    waggoner
  74. As    Phaethon    would    whip    you    to    the    west,
  75. And    bring    in    cloudy    night    immediately.
  76.  
  77. Put the cursor in the word 'you' (first row, third word), press  the  mouse
  78. button and, without releasing it, go to the word 'whip' in the  third  row,
  79. then release : you have selected the following region
  80. you    fiery-footed
  81. lodging;    such
  82. would    whip
  83.  
  84. even though all the words from 'you' to 'whip' are hilited.  We  have  thus
  85. selected columns 3-4 and rows 1-3.
  86. It is sometimes difficult to be sure what has been selected because columns
  87. are not aligned vertically so  you  can  check  this  using  the  <Colorize
  88. Columns> menu item : only the selected columns will be colorized like so
  89. Gallop    apace,    you    fiery-footed    steeds,
  90. Towards    Phoebus'    lodging;    such    a    waggoner
  91. As    Phaethon    would    whip    you    to    the    west,
  92. And    bring    in    cloudy    night    immediately.
  93.  
  94. So dragging the mouse from position (a,b) in a table to position (c,d) 
  95. selects columns 'a' to 'c' and rows 'b' to 'd'.
  96.  
  97. If you want to have a better vertical alignment of your columns you can use
  98. the <Equalize Columns> menu item. Select the region  as  above  and  select
  99. <Equalize Columns> in the <Columns> menu. The result will be :
  100. Gallop     apace,      you         fiery-footed    steeds,
  101. Towards    Phoebus'    lodging;    such            a          waggoner    
  102. As         Phaethon    would       whip            you        to              the    west,
  103. And        bring       in          cloudy          night      immediately.
  104.  
  105. By the way, equalizing makes it very easy to  use  rectangular  hiliting  :
  106. select a region with the mouse holding the option key down.
  107.  
  108.  
  109. -Columns separator-
  110. It must NECESSARILY be a SINGLE character. 
  111. Default is the tabulation character <\t>. 
  112. With Latex you might want to choose '&' as a separator for \array or \table
  113. environments:
  114.     \begin{tabular}{|c|c|c|}
  115.     \hline
  116.     you & fiery-footed \\
  117.     lodging; & such \\
  118.     would & whip \\
  119.     \hline
  120.     \end{tabular}
  121. You can even use the  'space'  character  as  a  separator.  See  also  the
  122. <Columns to Latex> item below.
  123.  
  124. -Caveat-
  125. * the cursor can be positioned anywhere in a "cell"  :  the  entire  column
  126. will always be selected.
  127.  
  128. * you do not have necessarily to colorize the selected region. This is just
  129. handy for visualisation. BEWARE  that  this  procedure  removes  all  other
  130. colors in your document (this proc might be improved later).
  131.  
  132. * columns are numbered from 1 to n (see the messages in the status bar).
  133.  
  134. * hiliting must still be there if you want to  apply  a  manipulation  like
  135. copying, inserting, appending, twiddling, deleting columns.
  136.  
  137. * note that (since version 0.5b) you DO NOT have anymore to escape (i-e put
  138. a backslash before) the special characters like 'backslash' \ or 'dollar' $
  139. or 'circumflex' ^ or 'endash'  -  etc.  The  package  takes  care  of  this
  140. internally. The tabulation character though is represented by '\t'.
  141.  
  142. * all the actions are undoable (with cmd-Z).
  143.  
  144.  
  145. -Text columnizing-
  146. There are tools to format text in vertical justified  columns  (single
  147. or multiple).  This  will  be  very  handy  to  prepare  nice  looking
  148. documentations, help files, etc. All the  paragraphs  in  the  present
  149. file have been justified with this tool. Everything is parametrizable:
  150. number of columns, left margin, text width.
  151. Here an example of multicolumnizing :
  152. Gallop  apace,        you    to the west, and bring in    That runaways'  eyes  may
  153. fiery-footed      steeds,    cloudy night immediately.    wink, and Romeo  leap  to
  154. towards Phoebus' lodging;    Spread thy close curtain,    these arms,  untalk'd-of,
  155. such  a    waggoner    as    love performing    night!    and unseen !
  156. Phaethon would  whip  you
  157.  
  158.  
  159. -More examples-
  160. You can now select a region and experiment : here are some examples applied
  161. to the previous selection.
  162.  
  163. 'Deleting'
  164. Gallop     apace,      steeds, 
  165. Towards    Phoebus'    a           waggoner    
  166. As         Phaethon    you         to              the        west,       
  167. And        bring       in          cloudy          night      immediately.
  168.  
  169. 'Copying, selecting the first two lines and appending'
  170. Gallop     apace,      you         fiery-footed    steeds,    you             fiery-footed
  171. Towards    Phoebus'    lodging;    such            a          waggoner        lodging;        such        
  172. As         Phaethon    would       whip            you        to              the             west,       
  173. And        bring       in          cloudy          night      immediately.
  174.  
  175. 'Copying, selecting the second column and inserting'
  176. Gallop     you         fiery-footed    apace,      you         fiery-footed    steeds,
  177. Towards    lodging;    such            Phoebus'    lodging;    such            a          waggoner    
  178. As         would       whip            Phaethon    would       whip            you        to              the    west,
  179. And        bring       in          cloudy          night      immediately.
  180.  
  181. 'Twiddling'
  182. Gallop     apace,      fiery-footed    you         steeds,
  183. Towards    Phoebus'    such            lodging;    a          waggoner    
  184. As         Phaethon    whip            would       you        to              the    west,
  185. And        bring       in          cloudy          night      immediately.
  186.  
  187. 'Sorting Columns'
  188. Gallop     apace,      lodging;    such            steeds,
  189. Towards    Phoebus'    would       whip            a          waggoner    
  190. As         Phaethon    you         fiery-footed    you        to              the    west,
  191. And        bring       in          cloudy          night      immediately.
  192.  
  193. 'Selecting the first two lines and reverse sorting rows'
  194. you             steeds,     apace,          Gallop          fiery-footed
  195. waggoner        Towards     such            Phoebus'        lodging;        a           
  196. As              Phaethon    would           whip            you             to              the    west,
  197. And             bring       in              cloudy          night           immediately.
  198.  
  199. 'Selecting all four lines and inserting rows numbers'
  200. 1    Gallop     apace,      you         fiery-footed    steeds,
  201. 2    Towards    Phoebus'    lodging;    such            a          waggoner    
  202. 3    As         Phaethon    would       whip            you        to              the    west,
  203. 4    And        bring       in          cloudy          night      immediately.
  204.  
  205. etc. etc.
  206.  
  207.  
  208. ====================
  209. Installation
  210. ====================
  211.  
  212. -Automatic installation-
  213. Open the "OPEN TO INSTALL" file. Opening this file indicates to Alpha  that
  214. a new package has to be installed  :  the  procedure  is  automatic.  Alpha
  215. knows where to store the different elements of your manipCols package.
  216.  
  217. -Manual installation-
  218. 1- put the "manipCols.tcl" file in the "Packages" subfolder  of  the  "Tcl"
  219. folder which is located at the same level as your Alpha application
  220. 2- put the "ManipCols Help" file in the "Help" folder located at  the  same
  221. level  as your Alpha application. Next time you launch Alpha, you will have
  222. a "ManipCols Help" item in the Help menu.
  223. 3- launch Alpha. You have to  rebuild  the  package  indices  and  the  Tcl
  224. indices. <Rebuild Package Indices> is in  the  Config->Packages  menu,  and
  225. <Rebuild Tcl Indices> is in the Tcl menu.
  226. 5-  quit Alpha and relaunch it : that's all there is to it.
  227.  
  228. -Activating the manipCols feature-
  229. Go to "Config-->Preferences-->Menus and Features" and select  'Manip  Cols'
  230. in the features list by checking the corresponding checkbox.
  231.  
  232. -After installing- 
  233. Have a look at the Manip Cols preferences in the <Packages> submenu of  the
  234. <Config> menu. More explanations below.
  235.  
  236.  
  237. ====================
  238. Menu Items
  239. ====================
  240.  
  241. Almost all of these items suppose you have selected columns : see above 
  242. how to select columns.
  243.  
  244. <Copy Columns>        Copy the selected columns in the MacOS system
  245.             scrap.  Note  that  if  no  region  has  been
  246.             selected or hilited,    the    entire    line
  247.             containing the cursor will be copied.
  248. <Insert Columns>    Insert columns from the system  scrap  BEFORE
  249.             the first selected column.
  250. <Append Columns>    Append columns contained in the system  scrap
  251.             to the  right  of  the  selected  lines.  The
  252.             procedure will append as much as it can :  if
  253.             you have selected a  region  with  less  rows
  254.             than the material  contained  in  the  system
  255.             scrap, it will ignore the remaining lines.
  256. <Twiddle Columns>    Exchange the leftmost and right most  columns
  257.             of your selection. Note that  there  must  be
  258.             enough elements on each    row    to    allow
  259.             twiddling : if not the  procedure  will  fail
  260.             and send  an  alert.  This  can  easily  been
  261.             solved by using the <Complete Rows> item.
  262. <Colorize Columns>    Colorize the selected items. This  is  useful
  263.             to visualize a selected  region  and  control
  264.             that it contains what you want.  Please  note
  265.             that you will lose any colorization  you  did
  266.             previously in your file. This point should be
  267.             improved later. So use with care.
  268. <Cut Columns>        Delete the selected columns and send  a  copy
  269.                         to the system  scrap  so  that  they  may  be
  270.                         pasted, inserted, appended elsewhere.
  271.                         All the columns to the right of the selection
  272.                         will be shifted left.
  273. <Delete Columns>    Delete the selected columns.
  274. <Equalize Columns>    This proc calculates the  maximum  length  of
  275.                         each of the selected columns and appends  the
  276.                         necessary amount of blank space so that  each
  277.                         column has a  unique  width.  This  allows  a
  278.                         perfect vertical alignment to make selections
  279.                         easier. Equalizing columns makes it very easy
  280.                         to use rectangular hiliting : select a region
  281.                         with the mouse holding the option key down.
  282.     When pressing the <option> key down, the previous item becomes :
  283. <Unequalize Columns>    This is the opposite of the previous items  :
  284.             any blank space at the right of a "cell" will
  285.             be trimed.
  286. <Right Justify>        To right justify the selected columns.
  287.     When pressing the <control> key down, the previous item becomes :
  288. <Left Justify>
  289.     When pressing the <option> key down, the previous item becomes :
  290. <Center>
  291.           This is easy to remember : the control, option  and  command
  292.           keys are in this order on the left of the  keyboard.  So  to
  293.           left justify, press the leftmost key  (<control>  key)  when
  294.           opening the menu etc.
  295.  
  296. <Complete Rows>        In case all the rows do  not  have  the  same
  297.             "length" (i-e number    of    items),    this
  298.             procedure will add empty   cells    to    the
  299.             incomplete rows.
  300. <Columnize Text>    To justify the selected text  :  it  is  left
  301.                         and right  justified    vertically    in    a
  302.                         rectangle. The values for the left margin and
  303.                         for the total text width can be set with  the
  304.                         <Set Margins> item. Default  values  in  Text
  305.                         mode are 5 and 75.
  306. <Multi Columnize Text>    To put text in multiple  columns  like  in  a
  307.                         newspaper. You are prompted in the status bar
  308.                         to choose  the  number  of  columns  (default
  309.                         value is 2).
  310.     When pressing the <option> key down, the previous item becomes :
  311. <Uncolumnize Text>    To  undo  the  previous  command  :  all  the
  312.                         columns of a table will be put one  over  the
  313.                         other in a single column.
  314. <Insert Rows Numbers>    Insert the number of the row at the beginning
  315.             of the selected lines. Numbers are  separated
  316.             by the current  separator  and  constitute  a
  317.             separate column.
  318.     When pressing the <option> key down, the previous item becomes :
  319. <Insert Numbers From...> The same as the previous except that you are
  320.             prompted to choose the starting  number.  The
  321.             last number reached in a  previous  numbering
  322.             is proposed as a default choice.
  323. <Sort Columns> or
  324. <Reverse Sort Columns>     with the <option> key
  325. <Num Sort Columns> or 
  326. <Reverse Num Sort Columns> with the <option> key
  327.             This allows different  kinds  of  sorting  of
  328.             columns in the selected region.  Sorting  can
  329.             be done in increasing or decreasing order, in
  330.             litteral (1 before 11 before 2) or  numerical
  331.             order (1 before 2 before 11). Sorting is case
  332.             insensitive. If several columns are  included
  333.             in the selected region,  sorting  applies  to
  334.             the left one.
  335. <Sort Rows> or
  336. <Reverse Sort Rows>     with the <option> key
  337. <Num Sort Rows>
  338. <Reverse Num Sort Rows> with the <option> key
  339.             This allows different  kinds  of  sorting  of
  340.             each  entire  row  in  the  selected  region.
  341.             Sorting can be done    in    increasing    or
  342.             decreasing order, in litteral  (1  before  11
  343.             before 2) or  numerical  order  (1  before  2
  344.             before 11). Sorting is case insensitive.
  345. <Columns Separator>    Change here the character    considered    as
  346.             columns separator.  Remember  that  you  must
  347.             choose a SINGLE character :if not, some procs
  348.             might not work properly. It can be of  course
  349.             the tabulation character represented  by  \t.
  350.             This menu item allows to do temporary changes
  351.             (as long as you do not quit Alpha). To change
  352.             the Columns Separator permanently go  to  the
  353.             manipCols Preferences.
  354. <Columns Bindings>    Brings a window with  information  about  the
  355.             key bindings  available  when  the  manipCols
  356.             package is active. See below.
  357. <Set Margins>        You will be prompted in  the  status  bar  to
  358.                         set the values for the left  margin  and  the
  359.                         total text width.
  360.  
  361.  
  362. ====================
  363. Key Bindings
  364. ====================
  365.  
  366. All the key bindings will use 'ctrl-c' (c for columns !). 
  367. Hit 'ctrl-c', release, then hit one of the following letters :
  368. <ctrl-c a>    to <a>ppend columns
  369. <ctrl-c b>    to show info about <b>indings
  370. <ctrl-c c>    to <c>opy columns
  371. <ctrl-c d>    to <d>elete columns
  372. <ctrl-c e>    to <e>qualize columns (left justified)
  373. <ctrl-c f>    to insert rows numbers <f>rom a certain value
  374. <ctrl-c i>    to <i>nsert columns
  375. <ctrl-c j>    to <j>ustify text (not columns)
  376. <ctrl-c k>    to <k>olorize <k>olumns
  377. <ctrl-c m>    to center columns (m for <m>iddle)
  378. <ctrl-c n>    to <i>nsert rows numbers
  379. <ctrl-c o>    to sort each row in increasing <o>rder
  380. <ctrl-c p>    to com<p>lete rows
  381. <ctrl-c r>    to <r>ight justify columns
  382. <ctrl-c s>    to change the columns <s>eparator
  383. <ctrl-c t>    to <t>widdle columns
  384. <ctrl-c u>    to <u>nequalize columns
  385. <ctrl-c v>    to set the margin <v>alues for columnizing
  386. <ctrl-c x>    to cut columns (e<x>tract them and copy in system scrap)
  387. <ctrl-c z>    to uncolumni<z>e
  388. If you use the 'More Cols' package (see  below),  you  four  more  key
  389. bindings :
  390. <ctrl-c h>    to convert a table to <h>tml code
  391. <ctrl-c l>    to convert a table to a <l>atex tabular environment
  392. <ctrl-c w>    to convert a <w>orld <w>ide <w>eb Html table to text
  393. <ctrl-c y>    to convert an arra<y> or tabular LaTeX environment to text
  394.  
  395.  
  396. ====================
  397. Preferences
  398. ====================
  399.  
  400. The <Manip Cols Prefs…> item in the <Packages> submenu of the <Config>
  401. menu allows you to make a few choices :
  402. - the <Columns Color> variable allows you to choose the color in which
  403. to colorize the selected columns.
  404. - the <Columns Separator> variable allows you to  choose  the  default
  405. character used to separate columns : this is the separator which  will
  406. be used each time you launch Alpha and as long as you do not  override
  407. this choice with the <Columns Separator> menu item.
  408. - the <Min Columns Width> variable allows you to set the minimum width
  409. allowed for columns when using the <Text Columnizing> tool.
  410.  
  411.  
  412. ====================
  413. Version History
  414. ====================
  415.  
  416. 0.1b    05/27/00    
  417.                         First writing of this package.
  418. 0.2b    05/29/00    
  419.                         Changed 'ctrl-k' to 'ctrl-c' for  keybindings.
  420.                         Rearranged the menu items.
  421. 0.3b    05/31/00    
  422.                         Added a <Cut Columns> item.  Added  tools  for
  423.                         text columnizing. Added new key bindings.
  424. 0.4b    06/02/00    
  425.                         Corrected  a  bug  in  backward  search.  Made
  426.                         changes for Alphatk compatibility.
  427. 0.5b    06/03/00    
  428.                         Made the  problem  of  special  characters  to
  429.                         escape invisible for the user  :  it  is  done
  430.                         internally. 
  431. 0.6b    06/03/00    
  432.                         Changed the  routine  to  split  a  region  in
  433.                         paragraphs. 
  434. 0.7b    07/01/00    
  435.                         Added items to convert a table  to  HTML  code
  436.                         or to a LaTeX tabular environment. Items to do
  437.                         the reverse. Html nested tables are handled.
  438. 0.8b    08/17/00    
  439.                         The conversion of  tables  to  Html  or  Latex
  440.                         formats are now an independant feature  coming
  441.                         as a complement to manipCols.
  442. 0.9b    09/20/00    
  443.                         Added a "Colums Tutorial" item to link to  the
  444.                         Example file.
  445. 1.0    10/06/00    
  446.                         Added procs to  justify  some  columns  (left,
  447.                         right, center). The columns  equalization  now
  448.                         work on the selected columns and  not  on  the
  449.                         entire table.
  450.  
  451. ====================
  452. More Cols Package
  453. ====================
  454.  
  455. The 'More Cols' Package (moreCols.tcl) adds a few more  capacities  to
  456. the 'Manip Cols' Package. It allows conversion of text tables  to  and
  457. from Html or Latex formats. When it is activated, a new submenu called
  458. <Tables Conversion> is added at the bottom of  the  Columns  menu.  It
  459. contains the following items :
  460. <Columns to Html>    Converts an ordinary text table to HTML  code
  461.                         to export to an Html document.
  462. <Columns to Latex>    Converts an ordinary text table  to  a  LaTeX
  463.                         'tabular' environment.
  464.     When pressing the <option> key down, the previous items become :
  465. <Columns to Html>
  466. <Latex to Columns>
  467.                         They convert an HTML table   or    a    Latex
  468.                         'tabular' (or 'array') environment    to    a
  469.                         simple text tabulated  with    the    current
  470.                         'columns separator'. Nested HTML  tables  are
  471.                         handled. 
  472.  
  473.  
  474. ====================
  475. Known problems
  476. ====================
  477.  
  478. -Troubleshooting-
  479. If sometimes a proc does not do what you expect it to do, it is very  often
  480. because you have changed the  columns  separator  and  still  think  it  is
  481. another one. For instance if you change the separator from '\t' to a  blank
  482. space ' ', any word will be considered in a different  column  whereas  two
  483. words separated by a tab will be considered in the same  column.  And  vice
  484. versa. 
  485.  
  486.  
  487. Please e-mail any problem or bug you encounter : <berdesg@easynet.fr>
  488.  
  489. Visit my Web page for updates and other Alpha utilities :
  490.  <http://perso.easynet.fr/~berdesg/alpha.html>
  491. There are modes for Metafont, Metapost, Omega, MPW and the Filters Menu.
  492.  
  493. Back to top of the page
  494.